Skip to main content

​
Memory Overview

BindAI provides a memory package for storing, retrieving, searching, and managing memory records through a common provider interface. The package includes a Memory facade, a MemoryProvider interface, a MemoryRegistry, and a MemoryManager. These components provide the core memory API. How memory is connected to an Agent, configured in Studio, or persisted across application executions depends on the relevant integration and provider implementation.

​
What Is Memory?

Memory provides an API for working with records that an application can store and retrieve. The core package separates memory operations from the underlying storage provider:
The Memory facade delegates storage operations to its selected provider and exposes a common interface to application code.

​
Core Components

​
Memory

Memory is the high-level interface for memory operations. It supports:
  • set(record) — store a memory record.
  • get(key, namespace="default") — retrieve a record.
  • search(query, namespace="default", limit=10, metadata=None) — search records.
  • delete(key, namespace="default") — delete a record.
  • exists(key, namespace="default") — check whether a record exists.
  • clear(namespace="default") — clear a namespace.
  • close() — close the provider when it exposes a callable close method.
The facade accepts a provider instance, a registered provider name, or None. When no provider is supplied, it selects the registered provider named memory. Example:
This uses the default memory provider. It does not select SQLite automatically.

​
MemoryProvider

MemoryProvider is the abstract base class for memory providers. Implementations must provide the following operations:
  • set
  • get
  • search
  • delete
  • exists
  • clear
A custom implementation must satisfy this interface to be accepted by MemoryRegistry.register.

​
MemoryRegistry

MemoryRegistry manages provider classes by name. Its API includes:
  • register(name, provider) — register a provider class.
  • provider(name) — retrieve a registered provider class.
  • providers() — return a copy of the provider registry.
  • unregister(name) — remove a provider registration.
  • clear() — remove all provider registrations.
Provider names are normalized to lowercase, and registration rejects empty names and classes that do not inherit from MemoryProvider. The registry is a package-level mechanism; its existence alone does not establish that Studio exposes provider registration or configuration.

​
MemoryManager

MemoryManager provides record-level lifecycle utilities. The implemented methods include:
  • should_promote(record) and promote(record) — determine whether a record should be promoted and, when applicable, change its type to semantic memory.
  • should_forget(record) and forget(record) — check whether a record’s expiration time has passed.
  • touch(record) — update access tracking.
  • reinforce(record, amount=0.25) — increase record importance.
  • decay(record, amount=0.05) and weaken(record, amount=0.1) — reduce record importance without allowing it to become negative.
  • set_expiration(record, days=...) and clear_expiration(record) — set or remove expiration metadata.
These are explicit record-management operations. Their existence does not mean the runtime automatically promotes, expires, or decays every stored record on a schedule.

​
Registered Built-in Providers

The current registry source registers the following provider names: These names are registered by bindai_memory.registry. Registration does not, by itself, guarantee that a provider’s external dependencies are installed, that its backend is reachable, or that it is exposed through Studio. Consult the relevant provider implementation and its configuration requirements before using a specific backend.

​
Custom Providers

The package supports registering custom providers that inherit from MemoryProvider. A custom provider must implement the abstract methods required by the interface. After registration, its name can be passed to Memory, provided the registration is available in the running application. This describes the package-level extension mechanism. It does not establish a Studio configuration workflow for custom providers.

​
Record Retrieval and Lifecycle Updates

The Memory.get implementation performs additional operations when a record is found successfully:
  1. It updates the record’s access information through MemoryManager.touch.
  2. It reinforces the record’s importance.
  3. It writes the updated record through the provider.
  4. It retrieves the record again and returns that result.
These updates are part of the Memory facade’s retrieval behavior in the inspected implementation. Other lifecycle operations, such as promotion and expiration checks, are separate manager methods and should not be described as automatic background processes without further implementation evidence.

​
Memory and Agent Execution

The memory package defines the storage and record-management API. It should not be confused with the code that integrates memory into Agent execution. Before documenting automatic conversation loading, automatic saving after an Agent run, persistence across workflow runs, or Studio memory configuration, verify those behaviors in the relevant Agent, runtime, and Studio source code.

​
Memory and Workflow State

Memory and workflow state have different responsibilities:
  • Memory provides operations on memory records through a provider.
  • Workflow state represents the state of a workflow execution.
Do not assume that selecting a memory provider changes workflow-state storage or that workflow-state persistence automatically persists memory records.

​
Memory and Knowledge

Memory and Knowledge are separate parts of the framework.
  • Memory exposes operations for storing and retrieving memory records.
  • Knowledge provides the framework’s knowledge and retrieval functionality.
Their coexistence in an application does not establish that they share storage, configuration, or lifecycle behavior.

​
Storage and Security

Choose a provider according to the application’s actual storage requirements and deployment environment. Memory records may contain sensitive application data. Consider access controls, credentials, backup protection, retention requirements, and deletion procedures for the selected backend. Avoid depending on undocumented internal database schemas as public APIs.

​
Summary

The BindAI memory package provides:
  • A common MemoryProvider interface.
  • A Memory facade for record operations.
  • A MemoryRegistry for built-in and custom provider classes.
  • A MemoryManager for record-level lifecycle utilities.
  • Registered provider implementations for in-memory, SQLite, vector, PostgreSQL, Pinecone, and Chroma storage.
Provider registration and package-level APIs are confirmed by the inspected source. Agent integration, Studio configuration, and individual backend behavior should be documented separately and only to the extent supported by their implementations.